Inside Macintosh: Mac OS 8 Toolbox Reference /

Chapter 4 - Dialog Manager Reference / Dialog Manager Resources

The Dialog Resource

CHANGED WITH THE APPEARANCE MANAGER

A dialog resource is a resource of type 'DLOG'. All dialog resources can be marked purgeable, and they must have resource ID numbers greater than 127.

You can use an extended dialog resource with the same resource ID as your dialog resource to provide additional features for your dialog box, including movable modal behavior, Appearance-compliant backgrounds and controls, and embedding hierarchies. To specify the items in an dialog box, you must provide an item list resource. Use the GetNewDialog function to create the dialog box defined in the dialog resource and extended dialog resource.

Figure 4-1 shows the format of a compiled dialog resource.

Figure 4-1 Structure of a compiled dialog ('DLOG') resource

The compiled version of a dialog resource contains the following elements:

• Rectangle. This determines the dialog box's dimensions and, possibly, its position. (The last element in the dialog resource usually specifies a position for the dialog box.)
• Window definition ID. See "Window Definition IDs" for descriptions of the ID constants that can be used in this field to specify Appearance-compliant modal, movable modal, or modeless dialog boxes.
• Visibility. If this is set to a value of 1 (as specified by the visible constant in the Rez input file), the Dialog Manager displays this dialog box as soon as you call the GetNewDialog function. If this is set to a value of 0 (as specified by the invisible constant in the Rez input file), the Dialog Manager does not display this dialog box until you call the Window Manager function ShowWindow.
• Close box specification. This specifies whether to draw a close box. Normally, this is set to a value of 1 (as specified by the goAway constant in the Rez input file) only for a modeless dialog box to specify a close box in its title bar. Otherwise, this is set to a value of 0 (as specified by the noGoAway constant in the Rez input file).
• Reference constant. This contains any value that an application stores here. For example, an application can store a number here that represents a dialog box type, in order to distinguish between a number of similar dialog boxes. As this information is stored in a window structure within the dialog structure, you can use the Window Manager function SetWRefCon at any time to change this value in the dialog structure for a dialog box, and you can use the Window Manager function GetWRefCon to determine its current value.
• Item list resource ID. This ID specifies the item list resource and the dialog font table resource that will be used with this dialog box.
• Window title. A string displayed in the dialog box's title bar only when the dialog box is modeless or movable modal.
• Alignment byte. This is an extra byte added if necessary to make the previous Pascal string end on a word boundary.
• Dialog box position. A constant specifying the position of the dialog box on the screen; see the discussion of window positioning constants in Macintosh Toolbox Essentials (page 4-126). If your application positions dialog boxes on its own, you shouldn't use these constants, because they may cause conflicts with the Dialog Manager.
  • If 0x0000 appears here (as specified by the kWindowDefaultPosition constant in the Rez input file), the Dialog Manager positions this dialog box according to the global coordinates specified in the rectangle element of this resource.
  • If 0xB00A appears here (as specified by the kWindowAlertPositionParentWindow constant in the Rez input file), the Dialog Manager positions the dialog box over the frontmost window so that the window's title bar appears.
  • If 0x300A appears here (as specified by the kWindowAlertPositionMainScreen constant in the Rez input file), the Dialog Manager centers the dialog box near the top of the main screen.
  • If 0x700A appears here (as specified in the Rez input file by the kWindowAlertPositionParentWindowScreen constant), the Dialog Manager positions the dialog box on the screen where the user is currently working.